From 848a8a792ea208f59ab406057acb1f8a0e4bd390 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 9 May 2020 22:24:00 -0400 Subject: [PATCH] docs: Update migration guide Add sections about GtkBin, GtkContainer and gtk_widget_destroy(). --- docs/reference/gtk/migrating-3to4.xml | 97 +++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) diff --git a/docs/reference/gtk/migrating-3to4.xml b/docs/reference/gtk/migrating-3to4.xml index 78a8c1fc94..ee5bc5ecf9 100644 --- a/docs/reference/gtk/migrating-3to4.xml +++ b/docs/reference/gtk/migrating-3to4.xml @@ -212,6 +212,27 @@ the replacement for gtk_main_iteration() is g_main_context_iteration(). + +
+ Reduce the use of gtk_widget_destroy() + + GTK4 introduces a gtk_window_destroy() api. While that is not available + in GTK3, you can prepare for the switch by using gtk_widget_destroy() + only on toplevel windows, and replace all other uses with + gtk_container_remove() or g_object_unref(). + +
+ +
+ Reduce the use of generic container APIs + + GTK4 removes gtk_container_add() and gtk_container_remove(). While there + is not always a replacement for gtk_container_remove() in GTK3, you can + replace many uses of gtk_container_add() with equivalent container-specific + APIs such as gtk_box_pack_start() or gtk_grid_attach(), and thereby reduce + the amount of work you have to do at the time of the switch. + +
@@ -560,6 +581,82 @@
+
+ Adapt to GtkBin removal + + The abstract base class GtkBin for single-child containers has been + removed. The former subclasses are now derived directly from GtkWidget, + and have a "child" property for their child widget. The affected classes + are: + + + GtkAspectFrame + GtkButton (and subclasses) + GtkComboBox + GtkFlowBoxChild + GtkFrame + GtkListBoxRow + GtkOverlay + GtkPopover + GtkRevealer + GtkScrolledWindow + GtkSearchBar + GtkViewport + GtkWindow (and subclasses) + + + To add a child, use the setter for the "child" property (e.g. + gtk_frame_set_child()) instead of gtk_container_add(). Adding a child + in a ui file with child still works. + +
+ +
+ Adapt to GtkContainer removal + + The abstract bas class GtkContainer for general containers has been + removed. The former subclasses are now derived directly from GtkWidget, + and have class-specific add and remove functions. The affected classes + are: + + + GtkActionBar + GtkBox (and subclasses) + GtkExpander + GtkFixed + GtkFlowBox + GtkGrid + GtkHeaderBar + GtkIconView + GtkInfoBar + GtkListBox + GtkNotebook + GtkPaned + GtkStack + GtkTextView + GtkTreeView + + + The most noticable change will be to use gtk_box_append() or gtk_box_prepend() + instead of gtk_container_add() for adding children to GtkBox, and the change + to use container-specific remove functions, such as gtk_stack_remove() instead + of gtk_container_remove(). Adding a child in a ui file with + child still works. + +
+ +
+ Adapt to gtk_widget_destroy() removal + + The function gtk_widget_destroy() has been removed. To explicitly destroy + a toplevel window, use gtk_window_destroy(). To destroy a widget that is + part of a hierarchy, remove it from its parent using a container-specific + remove api, such as gtk_box_remove() or gtk_stack_remove(). To destroy + a freestanding non-toplevel widget, use g_object_unref() to drop your + reference. + +
+
Adapt to GtkStyleContext API changes -- 2.30.2